This article examines how AGENTS.md files impact AI coding agents, showing that well-structured agent docs can boost code quality by up to 15% while poorly designed ones can hurt performance. It outlines seven patterns that work—like progressive disclosure, step-by-step workflows, decision tables, real-code examples, and pairing “don’ts” with “dos”—and warns against overexploration from excessive context or warnings.

• AGENTS.md quality swings are huge: good ones boost output as much as upgrading from Haiku to Opus, bad ones perform worse than having no doc at all.
• Keep it short (100-150 lines) with details pushed to reference docs—bloated files cause "overexploration" where agents burn tens of thousands of tokens on irrelevant context and produce worse results (one case: completeness dropped 25% after the agent read 80K extraneous tokens for a two-line config change).
• Concrete structure wins: numbered step-by-step workflows cut missing files from 40% to 10% (+25% correctness), decision tables boosted best_practices by 25%, and real 3-10 line code snippets raised code_reuse by 20%.
• Always pair "don'ts" with concrete "dos," and scope docs to modular subsystems (~100 files) rather than writing sprawling repo-wide guides.